<HTML><BODY>
<A NAME="dopy_-_distributed_objects_for_python">
<H1>DOPY - Distributed Objects for Python</H1>

<P>DOPY is a small distributed object system written entirely in Python.  It is
not intended to be CORBA compliant.  Instead, it aims to be extremely easy to
use and to support Python's dynamic nature - methods are invoked dynamically,
parameters are passed by copy.  Any python object that can be pickled can
automatically be passed as a parameter or a return value, and any Python object
can be published as a distributed object.  
<P>The current version of DOPY is an extremely immature alpha release.  Its only
supported protocol is TCP/IP, and you must have thread support to be able to use
it (there is a facility for non-threaded use, but it is entirely untested).
I've distributed it because others might find it useful (even in its current
state) and because I'm interested in the feedback of the Python development
community.  
<P>This is just a brief "README" file, see also the evolving <A
HREF="Manual.html">User Manual</A> for more in-depth information.  
<A NAME="installation">
<H2>Installation</H2>

<P>Unzip the distribution zip file into somewhere on your PYTHONPATH (preferably
in site-packages under your main python tree) and rename the "dopy-&lt;version
number&gt;" directory to "dopy".  From within that directory, just run
"dopyserver" (if your system understands #!, "python -i dopyserver" if not) to
start the server, then run "dopyclient &lt;serverhost&gt;" in another session
(you may omit the host parameter if connecting to the local host).  If
everything is working right, you should see the following output from the
client: 
<PRE>
   connecting to localhost:9600...
   test of basic method invocation ok
   test of keyword parms ok
   test of exceptions ok
</PRE> 
<P>Unfortunately, distutils does not currently provide for the installation of
documentation files.  However, documentation should work right from the
distribution tree.  Just point your browser right at README.html (as you may be
doing right now :-) or Manual.html.  You may want to copy the entire
distribution tree to wherever you like to store your documentation files.  
<A NAME="5-minute_tutorial">
<H2>5-Minute Tutorial</H2>

<P>DOPY is intended to be really easy to use.  To create a server object, all
you need to do is create a server instance, get the hub, and register the
object.  
<P>To create a TCP server, import the dopy.tcp module and create the server as
follows: 
<PRE>
   import dopy.tcp
   dopy.tcp.makeServer(9600)
</PRE> 
<P>This creates a TCP/IP server listening on port 9600.  
<P>The Hub is a singleton object that manages connections and provides a basic
set of services (much like a CORBA orb).  Get the hub with the getHub()
function: 
<PRE>
   hub = dopy.getHub()
</PRE> 
<P>To publish an object, you must call the hub's addObject() method with a name
and the object.  The name is the key that must be used when obtaining a proxy
for the object on the client side: 
<PRE>
   hub.addObject('myObject', anObject)
</PRE> 
<P>At this point you can use the hub.mainloop() to just sit there and process
messages.  In the threaded model, mainloop reads raw input and evaluates it so
that you may execute one-line python commands while it is servicing requests in
the background threads.  
<P>On the client side, you need only use the dopy.tcp.remote() function to use
the remote object: 
<PRE>
   import dopy.tcp
   obj = dopy.tcp.remote('localhost', 9600, 'myObject')
</PRE> 
<P>The parameters of this function are host name, port number, and object name
(the name used in the addObject() call on the server side).  Now you can call
any methods provided by the remote object just as you ordinarily would.  
<A NAME="limitations">
<H2>Limitations</H2>

<P>DOPY is not CORBA compliant.  To get all of the advantages of CORBA, use
Fnorb or ILU.  
<P>You do not have access to the non-method attributes of the remote object:
your only interface to the remote object is through method invocation.  
<P>At this time, DOPY requires threads.  There is non-threaded "select" based
code, but this is completely untested at this time.  
<A NAME="why_use_a_non-corba_distributed_object_system?">
<H2>Why Use a Non-CORBA Distributed Object System?</H2>

<P>As stated earlier, DOPY is not CORBA-compliant.  It is not suitable for use
between anything other than Python programs.  However, because it is
Python-specific, it has certain advantages over CORBA: 
<UL>

<LI> 
<P>You don't have to worry about maintaining and distributing stub files, method
resolution and invocation is performed on the server side.  
<LI> 
<P>Arbitrarily complex Python objects can be passed as parameters, return
values, and exceptions.  
<LI> 
<P>New protocols can easily be added to the system (CORBA facilitates multiple
protocols, but in my perusal of the Fnorb source code, adding a new protocol
appeared to be a non-trivial exercise; in DOPY, it's much easier).  
</UL>

<A NAME="code_contribution_policy">
<H2>Code Contribution Policy</H2>

<P>I'll gladly accept fixes, enhancements, and add-ons providing that the
contributor agrees that the changes may be distributed under the terms of the
current license.  
<A NAME="copyright_info">
<H2>Copyright Info</H2>

<P>Copyright (C) 1999,2001,2002 Michael A.  Muller 
<P>Permission is granted to use, modify and redistribute this document,
providing that the following conditions are met: 
<UL>

<LI> 
<P>This copyright/licensing notice must remain intact.  
<LI> 
<P>If the code is modified and redistributed, the modifications must include
documentation indicating that the code has been modified.  
<LI> 
<P>The author(s) of this code must be indemnified and held harmless against any
damage resulting from the use of this code.  
</UL>

<P>This code comes with ABSOLUTELY NO WARRANTEE, not even the implied warrantee
of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  </BODY></HTML>